2020.2

Itential Automation Gateway

On this page:

Device Inventories

Overview

Automation Gateway supports different concepts of device inventory. In its most simple form, a user supplies a JSON object with a name and a set of variables which are meaningful to the particular integration being used. For Ansible, that may be variables like ansible_host or ansible_user which come directly from the Ansible documentation.

In addition to integration-specific variables, there are also multiple sources that device inventory can originate from (depending on the integration). Currently, the two source types are "Internal", meaning they are created directly by interacting with Automation Gateway, and "External", meaning they are supplied as a file on the server and pulled into Automation Gateway by referencing the file path.

The following will describe which integrations are compatible with Automation Gateway's inventories, which variables are required and recommended for each integration, where you can go to learn more about non-Automation Gateway inventories and how to manage the various inventories via graphical user interface (GUI), or via API calls.

Inventory Compatibility

The following is a list of inventory types which are available on a per-integration basis.

Integration Internal External
Ansible Yes Yes
Netmiko No No
Nornir No Yes
Scripts Yes (Ansible) Yes (Ansible)
Terraform No No

Inventory Integration Variables

Below you will find a chart which describes the variables required, by Automation Gateway, to create an inventory device. For detailed Automation Gateway information regarding parameters, data types, etc please see the {automation gateway url}/app/apidocs endpoint for the specific inventory/integration in question. For detailed integration-specific information, please see the relevant documentation for that inventory system. The following link attempts to give you a proper starting point but may change over time as those sites and integrations change: Inventory Documentation.

Integration Required Variables Recommended Variables
Ansible None ansible_host, ansible_port, ansible_user, ansible_password, ansible_connection, ansible_network_os
Netmiko Not applicable Not applicable
Nornir None hostname, port, username, password, platform
Scripts See Ansible above. See Ansible above.
Terraform Not applicable Not applicable


Inventory Documentation

For inventory questions related to integrations such as Ansible or Nornir, please see the official guides to learn how to effectively create that type of inventory.

For inventory questions related to Automation Gateway, users can refer to our built-in swagger doc by hovering the cursor over the menu icon to the right of Automation Gateway and clicking the API Documentation - 2.0 link.

Figure 1: Swagger API

swagger

Inventory Sources (Internal vs External)

While the functionality of each integration will remain the same regardless of how you source your inventory devices, it is important to understand how Automation Gateway will behave in each scenario.

Internal Inventory

An Internal inventory source simply means that an External file path was not supplied, or not correctly loaded; therefore, you must manage your inventory exclusively through the GUI or APIs.

Pros

  • Inventory can be fully managed via API calls for end-to-end automation that does not have access to the underlying file system.

Cons

  • Certain inventory features of an integration must be adapted to fit inside of a JSON structure instead of other file formats supported by that integration (eg. YAML for Ansible, etc.).

External Inventory

An External inventory source indicates that you have supplied a correct path to the relevant inventory or configuration file for that integration. Due to the External file acting as the source of truth, Automation Gateway is unable to directly modify the file for you and "Internal" inventory is necessarily disabled. In order to modify an External inventory, one must directly update the file itself and prompt Automation Gateway to "Refresh" its knowledge of that inventory.

Pros

  • The full extent of native inventory options are available for each relevant integration (e.g., complicated ini groups and variables with Ansible).

Cons

  • The underlying filesystem must be kept up to date via file syncing protocols, scripts, cron jobs, or manual processes.

Managing Ansible Devices

This section covers how to create and manage Ansible devices via GUI or API.

Create

via API

Users can create an Internal device by making a POST call to /api/2.0/devices.

An example payload to create a Device to use with Ansible:

{
    "name": "hostname",
    "variables": {
        "ansible_...": "...",
    }
}

Users can create an Internal device group by making a POST call to /api/2.0/groups.

An example payload to create a Group to use with Ansible:

{
  "name": "example_group",
  "childGroups": [
    "example_child_group"
  ],
  "devices": [
    "example_host"
  ],
  "variables": {
    "ansible_...": "..."
  }
}

via GUI

Users can click the circled plus (+) button in the toolbar on the upper-left to start an interactive window to create a Device for Ansible.

Figure 2: Create Device

Device Create

Likewise, users can click the plus (+) button to start an interactive window to create a Device Group for Ansible.

Figure 3: Create Device Group

Group Create

View

via API

Users can view Ansible devices by making a GET call to /api/2.0/devices or /api/2.0/devices/{device_name}.

Users can view Ansible groups by making a GET call to /api/2.0/groups or /api/2.0/groups/{group_name}.

via GUI

In the left navbar under Devices, you will find all the devices and groups that users have created for use with Ansible.

Figure 4: Device View

Device View

Figure 5: Device Groups View

Group View

Update

via API

Users can update an Internal device by making a PUT call to /api/2.0/devices/{device_name}.

An example payload to update a Device to use with Ansible (this object represents the variables object):

{
  "ansible_...": "...",
}

Users can update an Internal device group by making a PUT call to /api/2.0/groups/{group_name}.

An example payload to update a Group to use with Ansible (this object represents the variables object):

{
  "ansible_...": "..."
}

via GUI

When a device is selected on the left panel, users can click the Edit button at the bottom of the page to edit the associated variables of the device.

Figure 6: Update Device

Device Update

When a device group is selected on the left panel, users can click the + button near the Devices tab at the top to edit the devices associated with that group. Additionally, users can select the Group Variables tab and click Edit at the bottom to edit the associated variables of the group.

Figure 7: Update Device Groups

Device Group Update

Remove

via API

Users can delete an Ansible device by making a DELETE call to /api/2.0/devices/{device_name}.

via GUI

When a device is selected on the left, hover the cursor on Delete at the bottom of the page and then confirm the deletion.

Figure 8: Delete Device

Device Delete

When a device group is selected on the left, hover the cursor over the vertically stacked dots at the top and confirm the deletion.

Figure 9: Delete Device

Group Delete